Added guides to environment management#8
Conversation
✅ Deploy Preview for earthscope-geolab-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
sarahw-earthscope
left a comment
sarahw-earthscope
left a comment
There was a problem hiding this comment.
The content of the new pages is fantastic!
The organization of the whole section now feels chaotic, however. What started as a single page of bullet-summary followed by expanded details for each option, now just feels super redundant with those more detailed options linking out to more pages. I'd love to see one overhead page with a brief summary of the different installation options (this should help users differentiate their use case), and then link to the sub-page for the guide on each one.
| - file: advanced_topics/env_mgmt.md | ||
| - file: advanced_topics/environments/managing_environments.md | ||
| - file: advanced_topics/environments/building_custom_images.md | ||
| - file: advanced_topics/environments/binder-for-images.md |
There was a problem hiding this comment.
Can you nest these three pages as sub-sections under the environment management section?
There was a problem hiding this comment.
Also, binder_for_images.md isn't showing up in the rendered preview because you've got hyphens instead of underscores in the filename.
|
|
||
| When you open GeoLab and select an environment when starting your server, you launch into a pre-configured virtual python environment. These environments typically include many commonly used geophysics tools, but we cannot include everything. Additional software and packages can be installed by users in GeoLab, with several options: | ||
|
|
||
| * [Ephemeral Installation:](#ephemeral-installation) Due to the ephemeral nature of the JupyterHub servers, packages installed on the server will only be valid for your current session and will not persist from one session to another. You will need to reinstall them each time you log back in to GeoLab, or add them to your notebooks as magic commands. |
There was a problem hiding this comment.
Add 'create a new python environment' with brief summary here
|
|
||
| ## Ephemeral Installation | ||
| For detailed instructions for installing packages in GeoLab see the [guide](./environments/managing_environments.md) | ||
|
|
There was a problem hiding this comment.
This section needs a lot of smoothing. It's not clear if they're supposed to keep reading here, or jump to the new guide.
Even if the page ends up being super short, it might make sense to put ephemeral installs in their own .md file just to keep it organized and readable.
| @@ -0,0 +1,159 @@ | |||
| # Creating Your Own Python Environment in GeoLab | |||
|
|
|||
| Python projects rely on add-on packages, which are collections of code that do useful things like process data, make maps, or analyze signals. Different projects often need different packages, or even different versions of the same package. An **environment** is a way to keep all of that organized in one tidy, self-contained workspace. | |||
There was a problem hiding this comment.
Add a clarification that they are already inside a conda environment when they launch GeoLab.
| conda env create -f environment.yml | ||
| ``` | ||
|
|
||
| Conda will figure out which versions of everything are compatible and download them. This can take a few minutes, which is normal. |
There was a problem hiding this comment.
We need to add clarification here that these things are getting installed in a NEW environment that doesn't include everything in the geolab-base. Their environment.yml needs to include all the packages they want to install, not just the ones that were missing from base.
| - python=3.11 | ||
| - ipykernel | ||
| - numpy | ||
| - matplotlib |
There was a problem hiding this comment.
Include explicit instructions for pip / requirements.txt , since many niche packages written by research labs aren't available on conda
|
|
||
| 1. Open a notebook and go to **Kernel > Change Kernel…** | ||
|
|
||
|  |
There was a problem hiding this comment.
images aren't rendering in the build preview, make sure they are included in the MR
| @@ -7,6 +7,8 @@ | |||
| * [Bring Your Own Image:](#bring-your-own-image) Many other organizations (e.g, NASA, NOAA) maintain their own JupyterHub compute environment images. Many of these will run in GeoLab. | |||
There was a problem hiding this comment.
Add a list item for binder
| ## Create a Custom Image | ||
| :::{attention} Section Under Development! | ||
| ::: | ||
| You can build a custom own image using our existing image as a template. This strategy is an advanced approach for software with complex installations, and only recommended for users with some prior knowledge of building containers. |
There was a problem hiding this comment.
These summaries now feel redundant with the summary bullets above and the details on a separate page.
| [2i2c guide to binderhub](https://docs.2i2c.org/user/environment/dynamic-imagebuilding/#user-environment-building) - This strategy is an option if you want to use an environment file that extends the base GeoLab image with additional python packages, but don't want to build and host an image. You can specify your environment file once to generate a stable container, and load that at launch time. Note, there's a 15-20 minute overhead to build the image in GeoLab the first time and any time you change the environment file, you will need to consider whether this will save you time in the long run. | ||
|
|
||
| - If you need to make extensive software changes, you can build your own image using our existing image as a template. Instructions are located in the `README.md` file in the [GeoLab GitHub repository.]({{ geolab_github }}) You will need to clone the repository, modify the build files to suit your needs, build your container and upload it to a public container registry like DockerHub or AWS ECR, and then select it as 'Other' from the dropdown when you [launch your GeoLab server](../getting_started/server_launch.md). This strategy is an advanced approach for software with complex installations, and only recommended for users with some prior knowledge of building docker containers. | ||
| Follow the instructions to deploy a custom image from a GitHub repository using binder in this [guide](./environments/binder_for_images.md). |
There was a problem hiding this comment.
It's confusing to have two links here (one to 2i2c, one to our guide), users won't know which one to follow. I'd suggest linking to our guide, and then at the end of that, add "see the 2i2c guide for additional details"
2 participants
added binder_for_images.md, building_custom_images.md, and managing_environments.md